CREATING INSTRUMENTS
====================

1. Open DevSound_SongData.asm.

2. Scroll down to InstrumentTable: (or use Ctrl-F* to search for "InstrumentTable:")

3. Add an entry at the bottom of the table for your instrument, like so:
	dins Bepis
NOTE: The instrument name given here is simply an example, you can replace it with whatever you want.

The pointer should now be set up. Now let's define the instrument!

4. Scroll down below, you should see a list with many entries that look something like this:
	ins_Foo:	Instrument	0,Foo,Foo,Foo,_
	ins_Bar:	Instrument	1,Bar,Bar,Bar,Bar
	ins_Baz:	Instrument	0,Baz,Baz,Baz,_
	ins_Boom:	Instrument	0,Boom,Boom,_,_

5. At the bottom of this list, add a new entry for your instrument. It should look something like this:
	ins_Bepis:	Instrument,0,Bepis,Bepis,Bepis,Bepis

NOTE: The names given here are simply examples, you can replace them with whatever you want.
(See Appendix 1 for the instrument format in detail.)

Our instrument is now defined, but there's something we're missing: the volume/arp/pulse/vibrato sequences. Let's take care of that.

6. Use Ctrl-F* to search for "Volume sequences", and add a new entry for vol_Bepis (or whatever you named it). It should look something like this:
	vol_Bepis:		db	15,14,13,12,11,10,9,8,7,6,5,4,3,2,1,0,$ff,0

NOTE: The data given here is an example, you can replace it with whatever you want.
(See Appendix 2 for the volume sequence format in detail.)

7. If you are creating a pulse instrument, scroll down to the arpeggio sequences (directly below the volume sequences) and add a new entry for arp_Bepis (or whatever you named it). It should look something like this::
	arp_Bepis:		db	0,4,7,12,$fe,0
	
If you are creating a noise instrument, It should look something like this:
	arp_Bepis:	db	24,12,10,18,s7+29,$fe,5

NOTE: The data given here is an example, you can replace it with whatever you want.
(See Appendix 3 for the arpeggio sequence format in detail.)

8. If you are creating a noise instrument, you're done! Otherwise, if you are creating a pulse instrument, scroll down to the pulse or wave sequences, and create a new entry for waveseq_Bepis. It should look something like this:
	waveseq_Bepis:	db,	0,0,0,0,1,1,1,1,2,2,2,2,3,3,3,3,$fe,0

NOTE: The data given here is an example, you can replace it with whatever you want.
(See Appendix 4 for the pulse sequence and wave sequence formats in detail.)

9. Scroll down to the vibrato sequences and add a new entry for vib_Bepis (or whatever you named it). It should look something like this:
	vib_Bepis:	db	16,1,2,3,2,1,0,-1,-2,-3,-2,-1,0,$fe,1
	
Note: The data given here is an example, you can replace it with whatever you want.
(See Appendix 5 for the vibrato sequence format in detail.)
	
10. You're done!

* That's Command-F if you're on a Mac.

APPENDIX 1: INSTRUMENT FORMAT
=============================

Instrument definitions follow the following format:
[reset flag],[volume pointer],[arp/noise pointer],[pulse/wave pointer],[vibrato pointer]

The reset flag is one byte. If bit 0 is set (+1), the pulse/wave pointer position will not be reset on a new note. If bit 1 is set (+2), the volume pointer position will not be reset on a new note.

The pulse/wave pointer and vibrato pointers are not used for noise instruments. It is recommended that you set these to _ for noise instruments.

If you do not want to use an arpeggio sequence, replace the arp/noise pointer field with _.

If you do not want to use a vibrato sequence, replace the vibrato pointer with _.

Note:
	vol_, arp_, waveseq_ and vib_ prefixes are automatically prepended to each respective pointer entry. So you don't have to include them when defining the instrument.
	id_<insname> constant is also generated from dins command in the instrument table. This is useful when you want to use this instrument's ID.

APPENDIX 2: VOLUME TABLE FORMAT
===============================

Each volume table is a sequence of bytes specifying volume values, followed by either a stop or loop command.

Volume values can be from 0 to 15, including wave channel (they will be automatically scaled)

To loop a volume sequence, use command $fe, followed by the loop point offset. Example: $fe,3 will jump to position 3.

To terminate a volume sequence, use command $ff.
NOTE: This will not cut the note. If you want the note to be cut when the volume sequence ends, you should add 0 to the end of the volume sequence, followed by the stop command.

To set a release point, use command $fd. The volume envelope will be held at the point specified until a "note release" command is triggered.

For pulse/noise channel, you must specify the final envelope after volume sequence termination command, this value corresponds directly to NRx2 value. Example: $ff,$37 will load volume 3 with envelope 7 after the table ends.

APPENDIX 3: ARP/NOISE SEQUENCE FORMAT
=====================================

Each arp/noise table is a sequence of bytes specifying transpose values, followed by either a stop or loop command.

Each transpose value between $00 - $3f will transpose the base note up by x semitones. Example: $c will transpose the note up by $c (or 12) notes.
Each transpose value between $40 - $7f will transpose the base note down by 128-x semitones. Example: $74 will transpose the note down by $c (or 12) notes.
Each transpose value between $80 - $da will use note x regardless of the base note. Example: $a9 will use note $29 (F-5).

For noise sequences, add s7 to the transpose value to get periodic noise (sounds more like a tone). Example: s7+29 = transpose up 29 semitones w/ periodic noise

To loop an arp/noise sequence, use command $fe, followed by the loop point offset. Example: $fe,3 will jump to position 3.

To terminate an arp/noise sequence, use command $ff.
NOTE: The transpose value will remain as whatever it was before the stop command. If this is not desirable, you should add 0 to the end of the arp/noise sequence, followed by the stop command.

APPENDIX 4: PULSE/WAVE SEQUENCE FORMAT
======================================

Each pulse/wave table is a sequence of bytes specifying pulse/wave values, followed by either a stop or loop command.

Pulse values can be 0 (12.5% pulse), 1 (25% pulse), 2 (50% pulse), or 3 (75% pulse). Anything else is not recommended.

Wave values can be anywhere from 0 to 254.
SPECIAL CASE FOR WAVE VALUES: Using $c0 as the wave value will enable the usage of the wave buffer, for use in conjunction with wave buffer commands (see Command reference.txt for a list of wave buffer commands). If there is nothing in the wave buffer, this will result in a blank wave!

To loop a pulse/wave sequence, use command $fe, followed by the loop point offset. Example: $fe,3 will jump to position 3.

To terminate a pulse/wave sequence, use command $ff.
NOTE: The pulse/wave value will remain as whatever it was before the stop command.

APPENDIX 5: VIBRATO SEQUENCE FORMAT
===================================

Each vibrato table is a sequence of bytes specifying pitch offset values (relative to base note), followed by a loop command.

The first byte of each vibrato sequence is the delay before the vibrato is triggered. This can be anything from 0 (instant vibrato) to 255. Lower values mean shorter delay.

For pitch offset values, the base offset (no offset) value is 0. Negative numbers can be used for negative pitch offsets.

To loop a vibrato sequence, use command $80, followed by the loop point offset. Example: $80,3 will jump to position 3.
NOTE: The loop point offset must be at least one, otherwise the delay value will be read as a pitch offset!

There is no stop command for vibrato sequences. Vibrato sequences must be terminated with a loop command (see above).
